﻿// ===============================================================================
// IXhtmlWriter.cs
// EOS Framework
// ===============================================================================
// Copyright (c) EOS Development Group. All rights reserved.
// ===============================================================================

namespace EOS.Framework.Web.Mvc
{
    /// <summary>
    /// Helper class for writing xhtml to a stream. The class also writes the xml-namespace and the doctype.
    /// </summary>
    public interface IXhtmlWriter
    {
        /// <summary>
        /// Starts writing an xml element.
        /// </summary>
        /// <remarks>
        /// Each started element must be ended to have a valid xml output.
        /// </remarks>
        /// <param name="localName">Name of the xml element. Cannot be null or empty or contains only blanks.</param>
        /// <exception cref="InvalidOperationException">The started xhtml tag cannot have childs.</exception>
        void WriteStartElement(string localName);

        /// <summary>
        /// Closes one element and pops the corresponding namespace scope.
        /// </summary>
        /// <remarks>If the opened element is a element, which cannot be empty the method
        /// writes the full end tag.</remarks>
        void WriteEndElement();

        /// <summary>
        /// Writes out the attribute with the specified local name and value to the last opened xml tag.
        /// </summary>
        /// <param name="name">The local name of the attribute.</param>
        /// <param name="value">The value of the attribute.</param>
        void WriteAttribute(string name, string value);

        /// <summary>
        /// Writes the given text content.
        /// </summary>
        /// <param name="text">Text to write.</param>
        /// <exception cref="InvalidOperationException">The started xml tag cannot have a value.</exception>
        void WriteString(string text);

        /// <summary>
        /// Writes raw markup manually from a string.
        /// </summary>
        /// <param name="data">String containing the text to write.</param>
        /// <remarks>This method does not escape special characters. When using this method, it cannot garantueed,
        /// that the class produces valid xhtml code.</remarks>
        void WriteRaw(string data);
    }
}
